This is a very brief introduction to RUTH
*****************************************
Basic usage
===========
Ruth has a CLI and should only be run from the directory in which it is located.
example run:

    ./ruth.py configuration.conf

To get help on it's usage:

    ./ruth.py --help

Configuration
=============
Ruth uses configuration files as input to running the suites.
Every configuration should at least have a section named 'global' and an option named 'modules' with a name of a module containing a suite.

Other available configurations are:
* Verbose - The verbosity level of the output when running the suite.
    1. Only show test reasults.
    2. Show tracebacks at the end of the run.
    3. Show tracebacks after every test.

The configuration file also needs to contain the minimal configuration needed for all the tests in the suite.

The Global Section
------------------
In the global section, in addition to Ruth's own configuration you can set options that are common to multiple test cases.
If a test case can't find an option in it's declared section it will also look for it in the global section.

Generating Sample Configurations
--------------------------------
If you want to test a suite and don't have a configuration for it you can run Ruth with the '-g MODULE, --generate-configuration=MODULE' option.
This will create a sample configuration from the templates of all the test cases in the suite.

Using Filters
=============

When you are fixing a specific bug sometime you want to run only some of the tests in the suite.
Because it is a *temporary* need creating a suite is way too much work.
For this Ruth has the '--filter-tests' (-f) option.
A filter is a glob expression that *filters* what tests should run.

Test IDs are in the format of ``<Module>.<TestCase>.<TestName>``.

Examples:
---------

You want to run only the tests from module 'foo':

    ruth.py -f "foo.*" config.conf

You want to run all the tests of a specific test case 'bar' in module 'foo':

    ruth.py -f "foo.bar.*" config.conf

You want to run all the tests that have 'spm' somewhere in their ID:

    ruth.py -f "*spm*" config.conf

You want to run all the volume tests but 'V' is cased differently in some tests:

    ruth.py -f "*[Vv]olume*" config.conf

You want to run all the tests except the tests containing 'domain' with either case in the first letter:

    ruth.py -f "^*[Dd]omain*" config.conf

.. note::
    globs **are** case sensitive

.. note::
    Don't forget the commas because otherwise bash will expand the glob **before** handing the arguments to RUTH.


How to add more tests ?
=======================

1. Copy template.py to mytest.py
2. Optional - Implement validateConfig()
3. Implement suite()
4. Implement tests
5. Generate sample config file. ``ruth.py -g <MODULENAME> <CONFIGPATH>``
6. Fill the config file
6. Run ``ruth.py <CONFIGFILE>``
7. Profit
